Give folders a folder schema for their own page and settings

What you'll see

A site has section pages – /Services/, /About/ – each with an introduction, a heading, menu text and a sort order, plus settings that apply to the whole site: the footer, the form recipient, the default meta description, labels like «Read more». The obvious shape is a document per concern inside the content tree: Services/Overview.docly for the section page, Settings/Common.docly for the settings, and folders such as Images/ or Graphics/ for files the pages link to.

It renders correctly, and nobody notices until the customer opens the workspace: half of what they see is not a page. They find a folder called Settings, a document called Overview in every section, and image folders next to the pages – and have to be told which ones they may touch.

What's actually happening

Docly already has a place for data that belongs to a folder rather than to a page in it: the folder schema. A schema whose Use this schema for is set to Folders (SchemaType: "Folder") defines the fields of the folder itself. The editor edits them in the folder's Properties, after Change type has given the folder that type. The values are stored in the folder's properties document (the .docly file in the folder in a docly clone) and travel with the folder.

• A section page is the folder's page. Its text, heading, page template and menu fields are folder fields. The listing template in #/Root/<Folder>/index.hash (or #/Folder/Index.hash) renders them.
• Not the workspace root. The root folder is the workspace and keeps the platform type Docly Workspace: its Properties hold the workspace's own fields – description, accepted content, columns and packages. Giving it the site's schema removes them, and changing the type back later replaces the properties document. Put the site-wide settings in #/Config (see Put configuration and secrets in the Config document). Make the front page a page at the root with its own document type, so templates find it by type, not by a name the customer can change.
• Images belong to the document or folder that shows them, in an image field – see Keep images out of rich text fields. With that, no helper folders of images are needed in the content tree.
• Accepted document types. A folder schema's AcceptTypes lists the document schemas the editor offers when creating something in that folder, so a Services folder offers a service page and nothing else.

Reading folder fields in a template (measured on a published site):

• docly.getFolder("/Services") returns the folder's fields plus Name, Path, Guid – but no Url. docly.getFolder("/") returns the root folder.
• docly.getFolders("/") returns every subfolder with its fields and Url – use it when you need a link or an image from a folder.
• An image field on a folder is served from the folder's own address: /Services/<id>. docly.linkFile(folder, folder.Image) builds the link from the Url of an item from getFolders. For the root folder, which has no Url, pass Object.assign({}, root, { Url: "/" }).

What to do

Do – a folder schema for the sections; the root stays a workspace:

1. Create the schemas in the designer with Use this schema for: Folders. A section schema has the page fields (title, meta description, heading, text, menu text and order, page template). The site-wide settings get a document schema for #/Config, and the front page a document schema of its own.
2. Give the folders their type: Properties → Change type (each section folder gets the section schema – leave the root as Docly Workspace), then fill in Properties. From the CLI, write the folder's .docly with "Schema": "<folder schema>" and push.
3. Render a section with #/Root/<Folder>/index.hash:

   #{
       let s = docly.getFolders("/", { name: "Services" })[0] || {};
       let items = docly.getFiles("/Services").filter(x => x.fileschema == "Service page");
   }#
   <h1>#docly.htmlEncode(s.Heading)#</h1>
   #s.Text#

4. Read the site-wide settings from #/Config in every template that needs them: let site = docly.getJson("#/Config") || {}; The front page: docly.getFiles("/").find(x => x.fileschema == "<Front page schema>"), rendered on / by #/Root/index.hash; its own template redirects /Front-page there with docly.redirect(request.sitepath).
5. Build the menu from what has a menu text – docly.getFolders("/") and docly.getFiles("/"), the front page included – sorted by a number field. Make that field a sortable column on the root folder (see Sort folder contents by a custom field): the customer orders the menu by dragging the rows, and the menu and the root listing stay in the same order.

Don't:

• a document named Overview or Index inside a section folder to carry that folder's text,
• the site's own schema on the workspace root – it replaces Docly Workspace,
• a Settings folder with a settings document in the content tree,
• folders of images (Images/, Graphics/) next to the pages.

Converting an existing site: the old CMS's structure (a section page as an item, a settings page, an uploads folder) is exactly what produces these documents. Move them onto the folders as part of the conversion – see Convert an existing website to Docly. Check the result in the workspace as the customer sees it: every item in a content folder should be a page.